/*
 * Copyright (c) 1995, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package java.awt;

import java.util.*;
import java.awt.peer.ChoicePeer;
import java.awt.event.*;
import java.util.EventListener;
import java.io.ObjectOutputStream;
import java.io.ObjectInputStream;
import java.io.IOException;

import javax.accessibility.*;


/**
 * The <code>Choice</code> class presents a pop-up menu of choices.
 * The current choice is displayed as the title of the menu.
 * <p>
 * The following code example produces a pop-up menu:
 *
 * <hr><blockquote><pre>
 * Choice ColorChooser = new Choice();
 * ColorChooser.add("Green");
 * ColorChooser.add("Red");
 * ColorChooser.add("Blue");
 * </pre></blockquote><hr>
 * <p>
 * After this choice menu has been added to a panel,
 * it appears as follows in its normal state:
 * <p>
 * <img src="doc-files/Choice-1.gif" alt="The following text describes the graphic"
 * style="float:center; margin: 7px 10px;">
 * <p>
 * In the picture, <code>"Green"</code> is the current choice.
 * Pushing the mouse button down on the object causes a menu to
 * appear with the current choice highlighted.
 * <p>
 * Some native platforms do not support arbitrary resizing of
 * <code>Choice</code> components and the behavior of
 * <code>setSize()/getSize()</code> is bound by
 * such limitations.
 * Native GUI <code>Choice</code> components' size are often bound by such
 * attributes as font size and length of items contained within
 * the <code>Choice</code>.
 * <p>
 *
 * @author Sami Shaio
 * @author Arthur van Hoff
 * @since JDK1.0
 */
public class Choice extends Component implements ItemSelectable, Accessible {

  /**
   * The items for the <code>Choice</code>.
   * This can be a <code>null</code> value.
   *
   * @serial
   * @see #add(String)
   * @see #addItem(String)
   * @see #getItem(int)
   * @see #getItemCount()
   * @see #insert(String, int)
   * @see #remove(String)
   */
  Vector<String> pItems;

  /**
   * The index of the current choice for this <code>Choice</code>
   * or -1 if nothing is selected.
   *
   * @serial
   * @see #getSelectedItem()
   * @see #select(int)
   */
  int selectedIndex = -1;

  transient ItemListener itemListener;

  private static final String base = "choice";
  private static int nameCounter = 0;

  /*
   * JDK 1.1 serialVersionUID
   */
  private static final long serialVersionUID = -4075310674757313071L;

  static {
        /* ensure that the necessary native libraries are loaded */
    Toolkit.loadLibraries();
        /* initialize JNI field and method ids */
    if (!GraphicsEnvironment.isHeadless()) {
      initIDs();
    }
  }

  /**
   * Creates a new choice menu. The menu initially has no items in it.
   * <p>
   * By default, the first item added to the choice menu becomes the
   * selected item, until a different selection is made by the user
   * by calling one of the <code>select</code> methods.
   *
   * @throws HeadlessException if GraphicsEnvironment.isHeadless() returns true
   * @see java.awt.GraphicsEnvironment#isHeadless
   * @see #select(int)
   * @see #select(java.lang.String)
   */
  public Choice() throws HeadlessException {
    GraphicsEnvironment.checkHeadless();
    pItems = new Vector<>();
  }

  /**
   * Constructs a name for this component.  Called by
   * <code>getName</code> when the name is <code>null</code>.
   */
  String constructComponentName() {
    synchronized (Choice.class) {
      return base + nameCounter++;
    }
  }

  /**
   * Creates the <code>Choice</code>'s peer.  This peer allows us
   * to change the look
   * of the <code>Choice</code> without changing its functionality.
   *
   * @see java.awt.Toolkit#createChoice(java.awt.Choice)
   * @see java.awt.Component#getToolkit()
   */
  public void addNotify() {
    synchronized (getTreeLock()) {
      if (peer == null) {
        peer = getToolkit().createChoice(this);
      }
      super.addNotify();
    }
  }

  /**
   * Returns the number of items in this <code>Choice</code> menu.
   *
   * @return the number of items in this <code>Choice</code> menu
   * @see #getItem
   * @since JDK1.1
   */
  public int getItemCount() {
    return countItems();
  }

  /**
   * @deprecated As of JDK version 1.1, replaced by <code>getItemCount()</code>.
   */
  @Deprecated
  public int countItems() {
    return pItems.size();
  }

  /**
   * Gets the string at the specified index in this
   * <code>Choice</code> menu.
   *
   * @param index the index at which to begin
   * @see #getItemCount
   */
  public String getItem(int index) {
    return getItemImpl(index);
  }

  /*
   * This is called by the native code, so client code can't
   * be called on the toolkit thread.
   */
  final String getItemImpl(int index) {
    return pItems.elementAt(index);
  }

  /**
   * Adds an item to this <code>Choice</code> menu.
   *
   * @param item the item to be added
   * @throws NullPointerException if the item's value is <code>null</code>
   * @since JDK1.1
   */
  public void add(String item) {
    addItem(item);
  }

  /**
   * Obsolete as of Java 2 platform v1.1.  Please use the
   * <code>add</code> method instead.
   * <p>
   * Adds an item to this <code>Choice</code> menu.
   *
   * @param item the item to be added
   * @throws NullPointerException if the item's value is equal to <code>null</code>
   */
  public void addItem(String item) {
    synchronized (this) {
      insertNoInvalidate(item, pItems.size());
    }

    // This could change the preferred size of the Component.
    invalidateIfValid();
  }

  /**
   * Inserts an item to this <code>Choice</code>,
   * but does not invalidate the <code>Choice</code>.
   * Client methods must provide their own synchronization before
   * invoking this method.
   *
   * @param item the item to be added
   * @param index the new item position
   * @throws NullPointerException if the item's value is equal to <code>null</code>
   */
  private void insertNoInvalidate(String item, int index) {
    if (item == null) {
      throw new
          NullPointerException("cannot add null item to Choice");
    }
    pItems.insertElementAt(item, index);
    ChoicePeer peer = (ChoicePeer) this.peer;
    if (peer != null) {
      peer.add(item, index);
    }
    // no selection or selection shifted up
    if (selectedIndex < 0 || selectedIndex >= index) {
      select(0);
    }
  }


  /**
   * Inserts the item into this choice at the specified position.
   * Existing items at an index greater than or equal to
   * <code>index</code> are shifted up by one to accommodate
   * the new item.  If <code>index</code> is greater than or
   * equal to the number of items in this choice,
   * <code>item</code> is added to the end of this choice.
   * <p>
   * If the item is the first one being added to the choice,
   * then the item becomes selected.  Otherwise, if the
   * selected item was one of the items shifted, the first
   * item in the choice becomes the selected item.  If the
   * selected item was no among those shifted, it remains
   * the selected item.
   *
   * @param item the non-<code>null</code> item to be inserted
   * @param index the position at which the item should be inserted
   * @throws IllegalArgumentException if index is less than 0
   */
  public void insert(String item, int index) {
    synchronized (this) {
      if (index < 0) {
        throw new IllegalArgumentException("index less than zero.");
      }
            /* if the index greater than item count, add item to the end */
      index = Math.min(index, pItems.size());

      insertNoInvalidate(item, index);
    }

    // This could change the preferred size of the Component.
    invalidateIfValid();
  }

  /**
   * Removes the first occurrence of <code>item</code>
   * from the <code>Choice</code> menu.  If the item
   * being removed is the currently selected item,
   * then the first item in the choice becomes the
   * selected item.  Otherwise, the currently selected
   * item remains selected (and the selected index is
   * updated accordingly).
   *
   * @param item the item to remove from this <code>Choice</code> menu
   * @throws IllegalArgumentException if the item doesn't exist in the choice menu
   * @since JDK1.1
   */
  public void remove(String item) {
    synchronized (this) {
      int index = pItems.indexOf(item);
      if (index < 0) {
        throw new IllegalArgumentException("item " + item +
            " not found in choice");
      } else {
        removeNoInvalidate(index);
      }
    }

    // This could change the preferred size of the Component.
    invalidateIfValid();
  }

  /**
   * Removes an item from the choice menu
   * at the specified position.  If the item
   * being removed is the currently selected item,
   * then the first item in the choice becomes the
   * selected item.  Otherwise, the currently selected
   * item remains selected (and the selected index is
   * updated accordingly).
   *
   * @param position the position of the item
   * @throws IndexOutOfBoundsException if the specified position is out of bounds
   * @since JDK1.1
   */
  public void remove(int position) {
    synchronized (this) {
      removeNoInvalidate(position);
    }

    // This could change the preferred size of the Component.
    invalidateIfValid();
  }

  /**
   * Removes an item from the <code>Choice</code> at the
   * specified position, but does not invalidate the <code>Choice</code>.
   * Client methods must provide their
   * own synchronization before invoking this method.
   *
   * @param position the position of the item
   */
  private void removeNoInvalidate(int position) {
    pItems.removeElementAt(position);
    ChoicePeer peer = (ChoicePeer) this.peer;
    if (peer != null) {
      peer.remove(position);
    }
        /* Adjust selectedIndex if selected item was removed. */
    if (pItems.size() == 0) {
      selectedIndex = -1;
    } else if (selectedIndex == position) {
      select(0);
    } else if (selectedIndex > position) {
      select(selectedIndex - 1);
    }
  }


  /**
   * Removes all items from the choice menu.
   *
   * @see #remove
   * @since JDK1.1
   */
  public void removeAll() {
    synchronized (this) {
      if (peer != null) {
        ((ChoicePeer) peer).removeAll();
      }
      pItems.removeAllElements();
      selectedIndex = -1;
    }

    // This could change the preferred size of the Component.
    invalidateIfValid();
  }

  /**
   * Gets a representation of the current choice as a string.
   *
   * @return a string representation of the currently selected item in this choice menu
   * @see #getSelectedIndex
   */
  public synchronized String getSelectedItem() {
    return (selectedIndex >= 0) ? getItem(selectedIndex) : null;
  }

  /**
   * Returns an array (length 1) containing the currently selected
   * item.  If this choice has no items, returns <code>null</code>.
   *
   * @see ItemSelectable
   */
  public synchronized Object[] getSelectedObjects() {
    if (selectedIndex >= 0) {
      Object[] items = new Object[1];
      items[0] = getItem(selectedIndex);
      return items;
    }
    return null;
  }

  /**
   * Returns the index of the currently selected item.
   * If nothing is selected, returns -1.
   *
   * @return the index of the currently selected item, or -1 if nothing is currently selected
   * @see #getSelectedItem
   */
  public int getSelectedIndex() {
    return selectedIndex;
  }

  /**
   * Sets the selected item in this <code>Choice</code> menu to be the
   * item at the specified position.
   *
   * <p>Note that this method should be primarily used to
   * initially select an item in this component.
   * Programmatically calling this method will <i>not</i> trigger
   * an <code>ItemEvent</code>.  The only way to trigger an
   * <code>ItemEvent</code> is by user interaction.
   *
   * @param pos the position of the selected item
   * @throws IllegalArgumentException if the specified position is greater than the number of items
   * or less than zero
   * @see #getSelectedItem
   * @see #getSelectedIndex
   */
  public synchronized void select(int pos) {
    if ((pos >= pItems.size()) || (pos < 0)) {
      throw new IllegalArgumentException("illegal Choice item position: " + pos);
    }
    if (pItems.size() > 0) {
      selectedIndex = pos;
      ChoicePeer peer = (ChoicePeer) this.peer;
      if (peer != null) {
        peer.select(pos);
      }
    }
  }

  /**
   * Sets the selected item in this <code>Choice</code> menu
   * to be the item whose name is equal to the specified string.
   * If more than one item matches (is equal to) the specified string,
   * the one with the smallest index is selected.
   *
   * <p>Note that this method should be primarily used to
   * initially select an item in this component.
   * Programmatically calling this method will <i>not</i> trigger
   * an <code>ItemEvent</code>.  The only way to trigger an
   * <code>ItemEvent</code> is by user interaction.
   *
   * @param str the specified string
   * @see #getSelectedItem
   * @see #getSelectedIndex
   */
  public synchronized void select(String str) {
    int index = pItems.indexOf(str);
    if (index >= 0) {
      select(index);
    }
  }

  /**
   * Adds the specified item listener to receive item events from
   * this <code>Choice</code> menu.  Item events are sent in response
   * to user input, but not in response to calls to <code>select</code>.
   * If l is <code>null</code>, no exception is thrown and no action
   * is performed.
   * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
   * >AWT Threading Issues</a> for details on AWT's threading model.
   *
   * @param l the item listener
   * @see #removeItemListener
   * @see #getItemListeners
   * @see #select
   * @see java.awt.event.ItemEvent
   * @see java.awt.event.ItemListener
   * @since JDK1.1
   */
  public synchronized void addItemListener(ItemListener l) {
    if (l == null) {
      return;
    }
    itemListener = AWTEventMulticaster.add(itemListener, l);
    newEventsOnly = true;
  }

  /**
   * Removes the specified item listener so that it no longer receives
   * item events from this <code>Choice</code> menu.
   * If l is <code>null</code>, no exception is thrown and no
   * action is performed.
   * <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
   * >AWT Threading Issues</a> for details on AWT's threading model.
   *
   * @param l the item listener
   * @see #addItemListener
   * @see #getItemListeners
   * @see java.awt.event.ItemEvent
   * @see java.awt.event.ItemListener
   * @since JDK1.1
   */
  public synchronized void removeItemListener(ItemListener l) {
    if (l == null) {
      return;
    }
    itemListener = AWTEventMulticaster.remove(itemListener, l);
  }

  /**
   * Returns an array of all the item listeners
   * registered on this choice.
   *
   * @return all of this choice's <code>ItemListener</code>s or an empty array if no item listeners
   * are currently registered
   * @see #addItemListener
   * @see #removeItemListener
   * @see java.awt.event.ItemEvent
   * @see java.awt.event.ItemListener
   * @since 1.4
   */
  public synchronized ItemListener[] getItemListeners() {
    return getListeners(ItemListener.class);
  }

  /**
   * Returns an array of all the objects currently registered
   * as <code><em>Foo</em>Listener</code>s
   * upon this <code>Choice</code>.
   * <code><em>Foo</em>Listener</code>s are registered using the
   * <code>add<em>Foo</em>Listener</code> method.
   *
   * <p>
   * You can specify the <code>listenerType</code> argument
   * with a class literal, such as
   * <code><em>Foo</em>Listener.class</code>.
   * For example, you can query a
   * <code>Choice</code> <code>c</code>
   * for its item listeners with the following code:
   *
   * <pre>ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class));</pre>
   *
   * If no such listeners exist, this method returns an empty array.
   *
   * @param listenerType the type of listeners requested; this parameter should specify an interface
   * that descends from <code>java.util.EventListener</code>
   * @return an array of all objects registered as <code><em>Foo</em>Listener</code>s on this
   * choice, or an empty array if no such listeners have been added
   * @throws ClassCastException if <code>listenerType</code> doesn't specify a class or interface
   * that implements <code>java.util.EventListener</code>
   * @see #getItemListeners
   * @since 1.3
   */
  public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
    EventListener l = null;
    if (listenerType == ItemListener.class) {
      l = itemListener;
    } else {
      return super.getListeners(listenerType);
    }
    return AWTEventMulticaster.getListeners(l, listenerType);
  }

  // REMIND: remove when filtering is done at lower level
  boolean eventEnabled(AWTEvent e) {
    if (e.id == ItemEvent.ITEM_STATE_CHANGED) {
      if ((eventMask & AWTEvent.ITEM_EVENT_MASK) != 0 ||
          itemListener != null) {
        return true;
      }
      return false;
    }
    return super.eventEnabled(e);
  }

  /**
   * Processes events on this choice. If the event is an
   * instance of <code>ItemEvent</code>, it invokes the
   * <code>processItemEvent</code> method. Otherwise, it calls its
   * superclass's <code>processEvent</code> method.
   * <p>Note that if the event parameter is <code>null</code>
   * the behavior is unspecified and may result in an
   * exception.
   *
   * @param e the event
   * @see java.awt.event.ItemEvent
   * @see #processItemEvent
   * @since JDK1.1
   */
  protected void processEvent(AWTEvent e) {
    if (e instanceof ItemEvent) {
      processItemEvent((ItemEvent) e);
      return;
    }
    super.processEvent(e);
  }

  /**
   * Processes item events occurring on this <code>Choice</code>
   * menu by dispatching them to any registered
   * <code>ItemListener</code> objects.
   * <p>
   * This method is not called unless item events are
   * enabled for this component. Item events are enabled
   * when one of the following occurs:
   * <ul>
   * <li>An <code>ItemListener</code> object is registered
   * via <code>addItemListener</code>.
   * <li>Item events are enabled via <code>enableEvents</code>.
   * </ul>
   * <p>Note that if the event parameter is <code>null</code>
   * the behavior is unspecified and may result in an
   * exception.
   *
   * @param e the item event
   * @see java.awt.event.ItemEvent
   * @see java.awt.event.ItemListener
   * @see #addItemListener(ItemListener)
   * @see java.awt.Component#enableEvents
   * @since JDK1.1
   */
  protected void processItemEvent(ItemEvent e) {
    ItemListener listener = itemListener;
    if (listener != null) {
      listener.itemStateChanged(e);
    }
  }

  /**
   * Returns a string representing the state of this <code>Choice</code>
   * menu. This method is intended to be used only for debugging purposes,
   * and the content and format of the returned string may vary between
   * implementations. The returned string may be empty but may not be
   * <code>null</code>.
   *
   * @return the parameter string of this <code>Choice</code> menu
   */
  protected String paramString() {
    return super.paramString() + ",current=" + getSelectedItem();
  }


    /* Serialization support.
     */

  /*
   * Choice Serial Data Version.
   * @serial
   */
  private int choiceSerializedDataVersion = 1;

  /**
   * Writes default serializable fields to stream.  Writes
   * a list of serializable <code>ItemListeners</code>
   * as optional data. The non-serializable
   * <code>ItemListeners</code> are detected and
   * no attempt is made to serialize them.
   *
   * @param s the <code>ObjectOutputStream</code> to write
   * @serialData <code>null</code> terminated sequence of 0 or more pairs; the pair consists of a
   * <code>String</code> and an <code>Object</code>; the <code>String</code> indicates the type of
   * object and is one of the following: <code>itemListenerK</code> indicating an
   * <code>ItemListener</code> object
   * @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
   * @see java.awt.Component#itemListenerK
   * @see #readObject(ObjectInputStream)
   */
  private void writeObject(ObjectOutputStream s)
      throws java.io.IOException {
    s.defaultWriteObject();

    AWTEventMulticaster.save(s, itemListenerK, itemListener);
    s.writeObject(null);
  }

  /**
   * Reads the <code>ObjectInputStream</code> and if it
   * isn't <code>null</code> adds a listener to receive
   * item events fired by the <code>Choice</code> item.
   * Unrecognized keys or values will be ignored.
   *
   * @param s the <code>ObjectInputStream</code> to read
   * @throws HeadlessException if <code>GraphicsEnvironment.isHeadless</code> returns
   * <code>true</code>
   * @serial
   * @see #removeItemListener(ItemListener)
   * @see #addItemListener(ItemListener)
   * @see java.awt.GraphicsEnvironment#isHeadless
   * @see #writeObject(ObjectOutputStream)
   */
  private void readObject(ObjectInputStream s)
      throws ClassNotFoundException, IOException, HeadlessException {
    GraphicsEnvironment.checkHeadless();
    s.defaultReadObject();

    Object keyOrNull;
    while (null != (keyOrNull = s.readObject())) {
      String key = ((String) keyOrNull).intern();

      if (itemListenerK == key) {
        addItemListener((ItemListener) (s.readObject()));
      } else // skip value for unrecognized key
      {
        s.readObject();
      }
    }
  }

  /**
   * Initialize JNI field and method IDs
   */
  private static native void initIDs();

/////////////////
// Accessibility support
////////////////


  /**
   * Gets the <code>AccessibleContext</code> associated with this
   * <code>Choice</code>. For <code>Choice</code> components,
   * the <code>AccessibleContext</code> takes the form of an
   * <code>AccessibleAWTChoice</code>. A new <code>AccessibleAWTChoice</code>
   * instance is created if necessary.
   *
   * @return an <code>AccessibleAWTChoice</code> that serves as the <code>AccessibleContext</code>
   * of this <code>Choice</code>
   * @since 1.3
   */
  public AccessibleContext getAccessibleContext() {
    if (accessibleContext == null) {
      accessibleContext = new AccessibleAWTChoice();
    }
    return accessibleContext;
  }

  /**
   * This class implements accessibility support for the
   * <code>Choice</code> class.  It provides an implementation of the
   * Java Accessibility API appropriate to choice user-interface elements.
   *
   * @since 1.3
   */
  protected class AccessibleAWTChoice extends AccessibleAWTComponent
      implements AccessibleAction {

    /*
     * JDK 1.3 serialVersionUID
     */
    private static final long serialVersionUID = 7175603582428509322L;

    public AccessibleAWTChoice() {
      super();
    }

    /**
     * Get the AccessibleAction associated with this object.  In the
     * implementation of the Java Accessibility API for this class,
     * return this object, which is responsible for implementing the
     * AccessibleAction interface on behalf of itself.
     *
     * @return this object
     * @see AccessibleAction
     */
    public AccessibleAction getAccessibleAction() {
      return this;
    }

    /**
     * Get the role of this object.
     *
     * @return an instance of AccessibleRole describing the role of the object
     * @see AccessibleRole
     */
    public AccessibleRole getAccessibleRole() {
      return AccessibleRole.COMBO_BOX;
    }

    /**
     * Returns the number of accessible actions available in this object
     * If there are more than one, the first one is considered the "default"
     * action of the object.
     *
     * @return the zero-based number of Actions in this object
     */
    public int getAccessibleActionCount() {
      return 0;  //  To be fully implemented in a future release
    }

    /**
     * Returns a description of the specified action of the object.
     *
     * @param i zero-based index of the actions
     * @return a String description of the action
     * @see #getAccessibleActionCount
     */
    public String getAccessibleActionDescription(int i) {
      return null;  //  To be fully implemented in a future release
    }

    /**
     * Perform the specified Action on the object
     *
     * @param i zero-based index of actions
     * @return true if the action was performed; otherwise false.
     * @see #getAccessibleActionCount
     */
    public boolean doAccessibleAction(int i) {
      return false;  //  To be fully implemented in a future release
    }

  } // inner class AccessibleAWTChoice

}
